﻿///////////////////////////////////////////////////////////////////////////////
///
/// Cylan Client Core
/// Copyright (C) Shenzhen Cylan Tech. Co., Ltd. 2012
///
/// @file       IBOX.h
/// @brief      IBOX云存储API
///
///////////////////////////////////////////////////////////////////////////////
#ifndef CYLAN_IBOX_H
#define CYLAN_IBOX_H

#include "Core/Core.h"
#include "Misc/StringBuffer.h"

#ifdef __cplusplus
extern "C"{
#endif

/**
 * @typedef IBOX_PATH_INFO
 * @brief IBOX路径信息
 */
typedef struct IBOX_PATH_INFO
{
    const char  *Name;          // 路径名称
    int         Hash;           // 路径Hash(最后修改时间)
    int         IsDirectory;    // 是否目录(0为文件,非0为目录)
    int         Size;           // 文件大小(只有IsDirectory为0时有意义)
} IBOX_PATH_INFO;

/**
 * @typedef PFNIBOX_PROGRESS_CALLBACK
 * @brief IBOX上传下载进度回调
 * @param Context 调用者指定的上下文
 * @param Current 当前已经传输字节数
 * @param Total 总共需要传输的字节数
 * @retval 0 继续传输
 * @retval 非0 中止传输
 *
 * @code
 * int IBOXProgressShow(void *Context, int Current, int Total)
 * {
 *   const char *Text = (const char *)Context;
 *   printf("%s Progress: [已传输%d字节/共%d字节]\n", Text, Current, Total);
 *   return 0; // 返回0继续传输, 返回1中止传输
 * }
 * @endcode
 *
 */
typedef int (* PFNIBOX_PROGRESS_CALLBACK)(void *Context, int Current, int Total);

/**
 * @enum IBOX_SHARE_ATTR
 * @brief IBOX共享类型
 */
typedef enum IBOX_SHARE_ATTR
{
    IBOXShareNone = 0 ,          // 取消共享
    IBOXShareGroup,             // 共享给同组用户
    IBOXShareAll,                // 共享给所有用户
    IBOXShareOther 				//�����ָ���飬���һ��id����
    
} IBOX_SHARE_ATTR;

/**
 * @fn CC_STATUS IBOXPathOpen(CHANDLE Session, const char *Path, CHANDLE *PathHandle)
 * @brief 打开IBOX路径
 * @param Session 已登陆会话句柄
 * @param Path IBOX路径, 可以是文件或文件夹路径
 * @param PathHandle 返回的路径句柄, 使用完后使用CHandleClose()释放
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 * @note 返回的Entry需要使用IBOXPathClose()函数释放.
 */
CC_STATUS IBOXPathOpen(CHANDLE Session, const char *Path, CHANDLE *PathHandle);

/**
 * @fn CC_STATUS IBOXPathInfo(CHANDLE PathHandle, IBOX_PATH_INFO *Info, int *ChildCount)
 * @brief 查询IBOX路径句柄信息
 * @param Parent 使用IBOXPathOpen打开的路径句柄
 * @param Info 返回的路径信息
 * @param ChildCount 返回的路径下文件/文件夹数量
 * @retval ERR_SUCCESS 操作成功
 * @note 此函数只返回执行IBOXPathOpen()瞬间路径下的文件状态, 多次执行并不会刷新.
 */
CC_STATUS IBOXPathInfo(CHANDLE PathHandle, IBOX_PATH_INFO *Info, int *ChildCount);


/**
 * @fn CC_STATUS IBOXPathInfoChild(CHANDLE PathHandle, int Index, IBOX_PATH_INFO *ChildInfo)
 * @brief 列出文件夹句柄下的文件/子文件夹
 * @param PathHandle 使用IBOXPathOpen打开的文件夹句柄
 * @param Index 索引号, 从0开始, 小于ChildCount
 * @param ChildInfo 返回的文件/子文件夹信息
 * @retval ERR_SUCCESS 查询成功
 * @retval ERR_NOT_FOUND 文件/路径不存在
 * @note 此函数只返回执行IBOXPathOpen()瞬间路径下的文件状态, 多次执行并不会刷新.
 */
CC_STATUS IBOXPathInfoChild(CHANDLE PathHandle, int Index, IBOX_PATH_INFO *ChildInfo);


/**
 * @fn CC_STATUS IBOXShare(CHANDLE Session, const char *Path, IBOX_SHARE_ATTR ShareType)
 * @brief 设置文件夹共享
 * @param Session 已登陆会话句柄
 * @param Path 设置共享属性的目录
 * @param ShareType 共享属性
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXShare(CHANDLE Session, const char *Path, IBOX_SHARE_ATTR ShareAttribute);

CC_STATUS IBOXShare_2(CHANDLE Session, const char *Path, IBOX_SHARE_ATTR ShareAttribute, int Share_Id);


/**
 * @fn CC_STATUS IBOXCreate(CHANDLE Session, const char *Path)
 * @brief 创建文件夹
 * @param Session 已登陆会话句柄
 * @param Path 创建文件夹的路径
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXCreate(CHANDLE Session, const char *Path);


/**
 * @fn CC_STATUS IBOXDelete(CHANDLE Session, const char *Path)
 * @brief 删除文件/文件夹
 * @param Session 已登陆会话句柄
 * @param Path 删除的路径
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXDelete(CHANDLE Session, const char *Path);


/**
 * @fn CC_STATUS IBOXCopy(CHANDLE Session, const char *From, const char *To)
 * @brief 复制文件
 * @param Session 已登陆会话句柄
 * @param From 源路径
 * @param To 目标路径
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXCopy(CHANDLE Session, const char *From, const char *To);


/**
 * @fn CC_STATUS IBOXMove(CHANDLE Session, const char *From, const char *To)
 * @brief 移动文件
 * @param Session 已登陆会话句柄
 * @param From 源路径
 * @param To 目标路径
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXMove(CHANDLE Session, const char *From, const char *To);


/**
 * @fn CC_STATUS IBOXRename(CHANDLE Session, const char *From, const char *To)
 * @brief 重命名文件
 * @param Session 已登陆会话句柄
 * @param From 源路径
 * @param To 目标路径
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXRename(CHANDLE Session, const char *From, const char *To);


/**
 * @fn CC_STATUS IBOXUpload(CHANDLE Session, const char *Path, const char *Name, const char *LocalFile, PFNIBOX_PROGRESS_CALLBACK ProgressCallback, void *Context)
 * @brief 上传文件
 * @param Session 已登陆会话句柄
 * @param Path 上传的路径
 * @param UploadName 上传后的文件名, 如果传NULL, 则使用LocalFile的文件名
 * @param LocalFile 本地上传的文件路径
 * @param ProgressCallback 进度汇报回调函数
 * @param Context 进度汇报回调函数的用户自定义参数
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_NOT_FOUND 本地文件读取失败
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXUpload(CHANDLE Session,
                     const char *Path,
                     const char *UploadName,
                     const char *LocalFile,
                     PFNIBOX_PROGRESS_CALLBACK ProgressCallback,
                     void *Context);


/**
 * @fn CC_STATUS IBOXDownload(CHANDLE Session, const char *Path, const char *DownloadFile, PFNIBOX_PROGRESS_CALLBACK ProgressCallback, void *Context)
 * @brief 下载文件
 * @param Session 已登陆会话句柄
 * @param Path IBOX文件所在路径
 * @param DownloadFile 本地下载后保存的文件路径
 * @param ProgressCallback 进度汇报回调函数
 * @param Context 进度汇报回调函数的用户自定义参数
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXDownload(CHANDLE Session,
                       const char *Path,
                       const char *DownloadFile,
                       PFNIBOX_PROGRESS_CALLBACK ProgressCallback,
                       void *Context);


/**
 * @fn CC_STATUS IBOXSearch(CHANDLE Session, const char *Pattern, CHANDLE *PathHandle, int *ResultCount)
 * @brief 搜索IBox
 * @param Session 已登陆会话句柄
 * @param Pattern 搜索的条件(可匹配部分文件名, 不支持通配符, 整个IBOX空间目录递归)
 * @param PathHandle 搜索结果保存的句柄, 使用CHandleClose()释放
 * @param ResultCount 搜索结果条目数量, 使用IBOXPathInfoChild()函数枚举PathHandle获取条目信息
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXSearch(CHANDLE Session, const char *Pattern, CHANDLE *PathHandle, int *ResultCount);


/**
 * @fn CC_STATUS IBOXGetExternalLink(CHANDLE Session, const char *Path, char *Output, int *Size)
 * @brief 获取外链路径(用于直接打开文件)
 * @param[in] Session 会话句柄
 * @param[in] Path IBOX文件路径
 * @param[out] Output 输出的外链路径
 * @param[in, out] Size 输入Output缓冲区的大小, 输出返回的外链长度
 * @retval ERR_BUFFER_TOO_SMALL 提供的Output缓冲Size过小
 * @retval ERR_SUCCESS 操作成功
 */
CC_STATUS IBOXGetExternalLink(CHANDLE Session, const char *Path, char *Output, int *Size);

/**
 * @fn CC_STATUS IBOXInitMountUserDir(CHANDLE Session)
 * @brief 初始化挂载盘
 * @param[in] Session 会话句柄
 * @retval ERR_SUCCESS 操作成功
 */
CC_STATUS IBOXInitMountUserDir(CHANDLE Session);

/**
 * @fn CC_STATUS IBOXGetSyncLog(CHANDLE Session, unsigned long long FromID, STRING_BUFFER *Result)
 * @brief 获取同步日志字符串
 * @param[in] Session 会话句柄
 * @param[in] FromID 获取同步日志的其实ID
 * @param[out] Result 返回的日志内容
 * @retval ERR_UNSUCCESS 其它
 * @retval 400 缺少参数或参数不正确
 * @retval 401 未登录或授权
 * @retval 404 日志版本不存在。假设服务器只保留最后1000条日志，服务器会删除以前的历史日志，此时客户端应该进行一次全面同步
 * @retval ERR_SUCCESS 操作成功
 */
CC_STATUS IBOXGetSyncLog(CHANDLE Session, unsigned long long FromID, STRING_BUFFER *Result);


/**
 * @fn CC_STATUS IBOXDownloadBySession(const char *Server,const char *Session,const char *Path,const char *DownloadFile,PFNIBOX_PROGRESS_CALLBACK ProgressCallback,void *Context)
 * @brief 下载文件
 * @Server 服务器地址
 * @param Session 已登陆会话句柄
 * @param Path IBOX文件所在路径
 * @param DownloadFile 本地下载后保存的文件路径
 * @param ProgressCallback 进度汇报回调函数
 * @param Context 进度汇报回调函数的用户自定义参数
 * @retval ERR_SUCCESS 操作成功
 * @retval ERR_IBOX_BAD_REQUEST 参数错误
 * @retval ERR_IBOX_VERIFY_FAILED 会话未登录
 * @retval ERR_IBOX_NOT_MODIFIED 文件未修改
 * @retval ERR_IBOX_NOT_FOUND 文件不存在
 * @retval ERR_IBOX_FILEEXIST 文件已存在
 * @retval ERR_IBOX_ISDIR 路径是目录
 * @retval ERR_IBOX_ISSHARE 路径已共享
 * @retval ERR_IBOX_DB_FAILED 数据库错误
 * @retval ERR_IBOX_FIELNAMEEXIST 文件名已存在
 * @retval ERR_IBOX_NONEMPTYDIR 非空目录
 * @retval ERR_IBOX_DELETEFAILED 删除失败
 * @retval ERR_UNSUCCESS 其他未知错误
 */
CC_STATUS IBOXDownloadBySession(const char *Server,
                       const char *Session,
                       const char *Path,
                       const char *DownloadFile,
                       PFNIBOX_PROGRESS_CALLBACK ProgressCallback,
                       void *Context);


/**
 * @fn void CURLGlobalInit()
 * @brief cURL全局初始化,只用于android session下载
 */
int CURLGlobalInit();

#ifdef __cplusplus
}
#endif

#endif /* CYLAN_IBOX_H */
